\chapter{Manual} % (fold)
\label{cha:manual}

Como ya se mencionó desde el capítulo \ref{cha:prototipo}, con la finalidad de
poner a prueba el diseño arquitectónico propuesto, construimos un prototipo de
la celda de almacenamiento.

En este apéndice se muestran las ideas e instrucciones necesarias para poner en
funcionamiento una celda de almacenamiento distribuida sobre una red de área
local.%, además de una explicación detallada de como utilizar el prototipo.

\section{Infraestructura necesaria} % (fold)
\label{sec:infraestructura}

Dada la implementación disponible del ADI~\cite{rabin}, la celda necesita al
menos de seis procesos, uno de ellos se desempeñará como el representante de la
celda, y los otros cinco, serán los EVA . Como se definió en la sección
\ref{sub:almacen}, un nodo interno, \index{nodo interno} puede albergar uno o
mas espacios virtuales de almacenamiento (EVA)\index{EVA}, cada uno de ellos es
un proceso independiente que cuenta con su propio archivo de configuración, su
propio conjunto de metadatos y un espacio exclusivo para que almacene los
bloques que reciba, tal como se muestra en la figura \ref{fig:nodointerno}, por
lo que la celda puede crecer en cuanto al número de nodos internos disponibles,
y los EVA que hospedan. Hay que mencionar que aunque el nodo representante
realizará tareas diferentes, el código que tiene disponible es el mismo que el
de los nodos internos, previendo que en un futuro, el diseño de la celda pueda
evolucionar para soportar la sustitución del nodo representante a partir de uno
de los nodos internos (ver figura \ref{fig:despliegue}).

\begin{figure}[ht]
 \centering
 \includegraphics[width=0.6\textwidth]{images/nodointerno}
 \caption{Varios EVA residentes en un nodo interno}
 \label{fig:nodointerno}
\end{figure}

Por lo anterior, la infraestructura necesaria para lograr los niveles de
calidad en el servicio del prototipo consta de:

\begin{itemize}

 \item Al menos cinco computadoras con las mismas capacidades, para
  desempeñarse como \textbf{nodos internos}.\index{nodos internos}

 \item Una computadora, equipada con dos interfaces de red, que le permitan
  comunicarse con los nodos internos y con una red externa, este equipo es el
  que se desempeñará como el nodo representante.\index{nodo representante}

 \item Un \textit{switch} \index{switch} para montar la red local en la que se
  conectarán los nodos que componen la celda. La capacidad de éste también
  tendrá un impacto significativo en el rendimiento de la celda.
\end{itemize}

\begin{figure}[ht]
 \centering
 \includegraphics[width=0.6\textwidth]{images/desplieguecelda}
 \caption{Posible configuración para la celda de almacenamiento}
 \label{fig:despliegue}
\end{figure}

% section infraestructura (end)

\section{Dependencias de software} % (fold)
\label{sec:dependencias}

Para funcionar correctamente, el prototipo depende de dos
componentes externos. Para ejecutar el código del EVA se necesita instalar en
cada uno de los nodos participantes un intérprete de Python y para gestionar
los metadatos se requiere PostgreSQL, dado que cada EVA necesita tener su
propia base de datos.

El procedimiento para instalar tanto Python\index{Python} como
PostgreSQL\index{PostgreSQL} varía dependiendo del sistema
operativo\index{Sistema Operativo}, por lo que detallarlo sale del alcance de
este trabajo.  

Una vez instalado PostgreSQL\index{PostgreSQL}, en el sistema se crea un
usuario llamado postgres, primero hay que asignarle una contraseña a este
usuario como se muestra en el listado \ref{lst:passpostgres}.

\begin{lstlisting}[style=consola, numbers=none, label=lst:passpostgres,
 caption=Cambiando la contraseña del usuario postgres]
 $ passwd postgres
 Changing password for postgres.
 New password: # ingresar nueva clave de acceso
 Reenter new password: # repetir nueva clave de acceso
 $
\end{lstlisting}

Una vez hecho esto, hay que crear una base de datos para cada uno de los EVA,
en este caso, dado que instalamos un manejador de base de datos en cada uno de
los nodos, hay que crear tantas bases de datos, como EVA's vayan a residir en
cada nodo, por ejemplo, si la base de datos se llamará \textit{celda}, entonces
hay que ejecturar los comandos mostrados en el listado \ref{lst:createdb}.

\begin{lstlisting}[style=consola, numbers=none, label=lst:createdb,
 caption=Creando una base de datos]
 $ su - posgres
 Password: # ingresar clave de acceso
 $ createdb celda
\end{lstlisting}

Ya con la base de datos creada, es recomendable crear un usuario dentro de
PostgreSQL\index{PostgreSQL} que sea exclusivo para la celda de almacenamiento,
un nombre apropiado puede ser \textit{admincelda} (ver listado
\ref{lst:createusr}).

\begin{lstlisting}[style=consola, numbers=none, label=lst:createusr,
 caption=Creando un usuario en PostgreSQL]
 $ createuser -DRSP admincelda
 Type password for new rol: 
 Retype it again: 
 $
\end{lstlisting}

Posteriormente hay que configurar PostgreSQL para que solicite su contraseña al
usuario al momento de intentar conectarse a la base de datos, esto se logra
editando el archivo \textit{data/pg\_hba.conf} dentro del directorio inicial
del usuario postgres (ver listado \ref{lst:edit}).

\begin{lstlisting}[style=consola, numbers=none, label=lst:edit,
 caption=Editando el archivo de pg\_hba.conf]
 $ su - postgres
 Password: # ingresar clave de acceso
 $ vim data/pg_hba.conf
\end{lstlisting}

En este archivo identificamos ejempos de cómo editar el archivo para permitir
el acceso a los usuarios, especificando las bases de datos a las que pueden
conectarse y el método de autenticación que emplearán para ello (listado
\ref{lst:ejemplos}).

\begin{lstlisting}[label=lst:ejemplos, caption=Ejemplos de configuración de
 acceso en el archivo pg\_hba.conf]
# local      DATABASE  USER  METHOD  [OPTIONS]
# host       DATABASE  USER  CIDR-ADDRESS  METHOD  [OPTIONS]
# hostssl    DATABASE  USER  CIDR-ADDRESS  METHOD  [OPTIONS]
# hostnossl  DATABASE  USER  CIDR-ADDRESS  METHOD  [OPTIONS]
\end{lstlisting}

Suponiendo que la base de datos se llama celda y el usuario se llama
admincelda, hay que instertar una línea en el archivo como la que se muestra en
el listado \ref{lst:acceso}.

\begin{lstlisting}[label=lst:acceso, caption=Permitiendo el acceso al usuario
 admincelda para la base de datos celda]
 local celda admincelda md5
\end{lstlisting}

Lo cual le indica a PostgreSQL\index{PostgreSQL} que el usuario
\textit{admincelda} pude conectarse desde el equipo \textit{local} (localhost)
a la base de datos \textit{celda} utilizando su contraseña, la cual será
protegida por el algoritmo MD5\index{MD5}. % Si lo que se quiere es permitir que
% el usuario se conecte a la base de datos desde otro equipo, la entrada en el
% archivo \textit{data/pg\_hba.conf} se verá mas o mensos así

Luego de esto es necesario reiniciar el servicio de
PostgreSQL\index{PostgreSQL}, nuevamente, esto es diferente en función del
sistema operativo\index{Sistema Operativo} que se esté utilizando.

\section{Instalación de los nodos} % (fold)
\label{sec:instalanodos}

Para tener instalado el prototipo, hay que copiar el código fuente en cada uno
de los nodos internos que van a formar parte de la celda. Por cada
EVA\index{EVA} en un nodo interno, se necesita:

\begin{enumerate}
 \item Un archivo de configuración\index{configuración, archivo de}.
 \item Una base de datos\index{base de datos}.
 \item Un directorio en el que almacenará los bloques\index{bloque} que reciba
  en resguardo.
\end{enumerate}

El archivo de configuración es contiene listas de pares \textbf{clave =
valor} separadas en secciones, que especifican valores como el puerto por el
que el EVA escuchará las peticiones de sus vecinos, el directorio en el que
almacenará los bloques\index{bloque} etc. (ver figura \ref{fig:despliegue}). En
el listado \ref{lst:configura} se muestra un ejemplo del archivo de
configuración.

\begin{lstlisting}[ label=lst:configura, caption=Plantilla de un archivo de
 configuración para lun EVA o el nodo representante]

 [General]
 address  = 192.168.0.1  # Direccion donde se hospeda el EVA
 port     = 4242         # Puerto asignado al EVA
 storage  = /storage/eva # Directorio para almacenar los bloques
 msu      = 10M          # UMA 

 [DataBase]

 dbname   = celda        # Nombre de la base de datos
 user     = admincelda   # Usuario que se conecta a la base de datos
 password = algunaclave  # Clave del usuario 

 [Log] 

 logfile  = /var/log/celda/celda.log # archivo de bitacoras

 [IDA] # Rutas hacia los algoritmos de dispersion y recuperacion
 
 disperse = /ruta/hacia/ida/dis
 recover  = /ruta/hacia/ida/rec

\end{lstlisting}

Por cada uno de los EVA\index{EVA} residentes en un nodo es necesario que
exista un archivo de configuración como este, los datos que aparecen en él
indican entre otras cosas el tamaño de la UMA\index{UMA}, el puerto por el que
el proceso escuchará las peticiones, el directorio en el que se almacenarán
los bloques \index{bloque}, la ruta hacia los programas encargados de codificar
los bloques usando el ADI y la ruta hacia el archivo en el que se almacenarán
las bitácoras.

Una vez creado el archivo de configuración \index{configuración, archivo de} el
siguiente paso es crear los directorios necesarios, el directorio en el que se
van a almacenar los bloques, y el directorio del archivo de bitácoras.

Por defecto, el sistema buscará el archivo de configuración
\index{configuración, archivo de} en el directorio
\textit{/etc/celda/celdad.conf}, asumiendo que el sistema se está ejecutando en
un ambiente Linux\index{linux}, si no es el caso, la ruta hacia el archivo de
configuración puede especificarse mediante la opción correspondiente (ver
sección \ref{sec:start}).

Para copiar el código a todos los nodos internos, puede usarse cualquier medio,
desde simplemente copiarlo en un dispositivo de almacenamiento, como una
memoria USB, subirlo a un servidor y descargarlo en cada uno de los nodos.

Una vez que el código se ha colocado en su lugar, hay que agregarlo 
a las variables de entorno PATH\index{PATH, variable
de entorno} y PYTHONPATH \index{PYTHONPATH, variable de entorno}; la primera es
necesaria para poder invocar el servicio de la celda solamente por su nombre
(celdad), \index{celdad} y la segunda es necesaria para que el intérprete de
Python \index{Python, intérprete de} pueda encontrar los paquetes que componen
el prototipo. \index{prototipo} De nuevo, la forma de hacer esto varía según el
sistema operativo que se esté utilizando.

Cuando ya se tiene todo acomodado en su lugar, es necesario construir las bases
de datos para cada uno de los EVA y el representante de la celda; como ya hemos
dicho con anterioridad, el código tanto de los EVA como del nodo representante
es idéntico y en consecuencia, la estructura de la base de datos para cada uno,
también lo es. Junto con el código del prototipo se proporciona un script
llamado \textit{install}, cuya finalidad es crear las tablas necesarias para el
funcionamiento de los nodos. Es recomendable consultar las opciones disponibles
en este comando mediante la opción \textit{--help}, como se muestra en el
listado~\ref{lst:instayuda}.  

\begin{lstlisting}[style=consola, numbers=none, label=lst:instayuda,
 caption=Opciones del comando para construir la base de datos.]

$ ./install --help
Usage: install [options]

Options:
  -h, --help            show this help message and exit
  -m MACHINES, --machines=MACHINES
                        Sets machines file
  -u USERS, --users=USERS
                        Sets users file
  -c CONF, --conf=CONF  
	
\end{lstlisting}

Los valores que deben ser proporcionados en las opciones del listado
\ref{lst:instayuda} son las siguientes:

\begin{description}
 \item[-m, --machines] Recibe la ruta hacia un archivo que contiene una lista
  de los EVA que formarán parte de la celda de almacenamiento, en el listado
  \ref{lst:maquinas} se muestra un ejemplo de como luce este archivo.

 \item[-u, --users] Recibe la ruta hacia un archivo que contiene una lista de
  usuarios, esta opción se utiliza para dar de alta usuarios de prueba, en el
  listado \ref{lst:usuarios}, se muestra un ejemplo de como luce este archivo.

 \item[-c, --config] Reciba la ruta hacia un archivo de configuración con el
  formato mostrado en el listado \ref{lst:configura}.
\end{description}

\begin{lstlisting}[ label=lst:maquinas, caption=Ejemplo de un archivo que
 contiene la lista de EVAs para dar de alta en la base de datos]
# Add to this file your SAD virtual spaces, in this format
# Agrega a este archivo los datos de tus espacios virtuales
# de almacenamiento, de acuerdo con el siguiente formato:
#
# [nombre] protocolo://direccion [puerto] [capacidad]
#
# Donde:
# 
#   * [nombre] ............ Es el nombre del EVA.
#   * protocol://hostname . Es la URI donde se hospeda el EVA.
#   * [puerto] ............ Puerto asignado al EVA.
#   * [capacity] .......... Indica la capacidad (en Bytes) del EVA.

arte01 http://192.168.3.142 4242 209715200
arte02 http://192.168.3.143 4242 209715200
arte03 http://192.168.3.144 4242 209715200
arte04 http://192.168.3.145 4242 209715200
arte05 http://192.168.3.146 4242 209715200

\end{lstlisting}

\begin{lstlisting}[ label=lst:usuarios, caption=Ejemplo de un archivo que
 contiene la lista de usuarios para dar de alta en la base de datos]


# Tabla de usuarios de prueba.
# Usuario  Clave          Nombre real        Correo        Servicio
root       passroot       Celda              root@arte        1
diego      passdiego      Diego Guzman       diego@arte       1

\end{lstlisting}

Suponiendo que los archivos de los listados \ref{lst:configura},
\ref{lst:maquinas} y \ref{lst:usuarios} se llaman \textit{celdad.conf},
\textit{maquinas.conf} y \textit{usuarios.conf} respectivamente, y que todos se
encuentran en el directorio \textit{/etc/celda/}, el script \textit{install} se
puede invocar como se muestra en el listado \ref{lst:instalar}

\begin{lstlisting}[style=consola, numbers=none, label=lst:instalar,
 caption=Creando la base de datos de un
 EVA o el nodo representante.]

$ cd /ruta/hacia/el/script
$ ./install -c /etc/celda/celdad.conf -m /etc/celda/maqunas.conf \
-u /etc/celda/usuarios.conf
	
\end{lstlisting}

% section instalanodos (end)

\section{Iniciando el servicio de almacenamiento} % (fold)
\label{sec:start}

Una vez instalados correctamente todos los componentes, es posible iniciar los
servicios en los nodos participantes, tanto en los internos, como en el
representante, tomando en cuenta que el nodo representante debe ser aquel que
es visible desde el exterior de la red en que se encuentran los otros nodos
(ver figura \ref{fig:despliegue}).

\begin{lstlisting}[style=consola, numbers=none, label=lst:uso, caption=Uso del
 prototipo]
 $ celdad -h
 Usage: celdad [options]

 Options:
   -h, --help            show this help message and exit
     -c CONFIG, --config=CONFIG
                              Config file
     -m MODE, --mode=MODE  proxy | node 
\end{lstlisting}

Los valores que deben ser proporcionados en las opciones del listado
\ref{lst:uso} son las siguientes:

\begin{description}
 \item[-m, --mode] Tiene dos posibles valores: \textit{proxy} y \textit{node},
  los cuales le indican al programa, respectivamente, si el nodo va a
  desempeñar el rol de nodo representante, o espacio virtual de almacenamiento.

 \item[-c, --config] Reciba la ruta hacia un archivo de configuración con el
  formato mostrado en el listado \ref{lst:configura}.
\end{description}

Hay que destacar que estos dos valores son opcionales, si ninguno de ellos es
especificado, el sistema se iniciará por defecto en modo \textit{node}, el cual
corresponde a que el nodo desempeñe el rol de espacio virtual de almacenamiento
(EVA\index{EVA}), y el archivo de configuración\textit{configuración, archivo
de} que intentará leer es \textit{/etc/celda/celdad.conf} y en caso de que éste
último no exista, el sistema lanzará una excepción, por lo tanto, si se desea
iniciar que el nodo será un EVA, y el archivo de configuración es el
predeterminado, el sistema puede inicializarse simplemente llamando al script
\textit{celdad} sin ningún parámetro (ver el listado \ref{lst:sinparam}), y en
caso de que se desee iniciar el sistema como nodo representante, hay que
especificar el parámetro \textit{--m proxy} o
\textit{-\hspace{0.1em}-mode=proxy} según se prefiera (ver el listado
\ref{lst:conparam}).

\begin{lstlisting}[style=consola, numbers=none, label=lst:sinparam,
 caption=Iniciar un EVA sin especificar ningún parámetro al inicio]
$ celdad
	Listening Port: 4242
	Storage Path:   /storage/celda
	MSU:            10485760 bytes
\end{lstlisting}

\begin{lstlisting}[style=consola, numbers=none, label=lst:conparam,
 caption=Iniciar al representante de la celda especificando el parámetro
 \textit{-\hspace{0.1em}-mode}]
$celdad --mode=proxy
	Listening Port: 4242
	Storage Path:   /storage/celda
	MSU:            10485760 bytes
\end{lstlisting}

En ambos casos, el comando reporta en su salida el puerto por el que escucha
las peticiones, el directorio donde almacenará los bloques que reciba y el
tamaño en bytes de la MSU\index{MSU}. En el momento en que todos los nodos
participantes estén activos, la celda estará lista para ser utilizada a través
del cliente.

\section{Uso del cliente} % (fold)
\label{sec:cliente}

La aplicación cliente también cuenta con su archivo de configuración, que
aunque más sencillo, también contiene datos importantes. Un ejemplo de este
archivo de configuración es el que se muestra en el listado
\ref{lst:clienteconf}.

\begin{lstlisting}[style=consola, numbers=none, label=lst:clienteconf,
 caption=Ayuda para el cliente de la celda]
[General]

# URL del representante de la celda.
proxy     = http://192.168.86.99:4242

# Directorio local en el que se guardaran los datos recuperados.
downloads = /home/diacus/Descargas

# Cantidad maxima de intentos fallidos para conectarse a la celda.
maxtries  = 3

[Log]

# Archivo de bitacoras para el cliente.
logfile   = /home/diacus/.celda/celda.log

\end{lstlisting}

El cliente de la celda de almacenamiento es una aplicación con una interfaz de
línea de comandos. Una pequeña ayuda de cómo invocar el cliente para conectarse
a la celda se muestra en el listado \ref{lst:clientehelp}.

\begin{lstlisting}[style=consola, numbers=none, label=lst:clientehelp,
 caption=Ayuda para el cliente de la celda]
$ celda -h
Usage: celda [options]

Options:
  -h, --help            show this help message and exit
  -c CONFIG, --config=CONFIG
                        Config file
  -u USER, --user=USER  User name
  -p PROXY, --proxy=PROXY
                        Proxy's URL
\end{lstlisting}

Típicamente es necesario especificar la url del representante y el nombre del
usuario para conectarse a la celda; acto seguido, se le solicitará la
contraseña del usuario especificado (ver el listado \ref{lst:inicio}).

\begin{lstlisting}[style=consola, numbers=none, label=lst:inicio,
 caption=Conectando el cliente a la celda de almacenamiento]
$ celda -u admin -p http://192.168.3.142:4242
Password: *******
celda:> _
\end{lstlisting}

Una vez conectado al sistema, el usuario puede interactuar con la celda mediante
el uso de los comandos disponibles, los cuales se muestran en la tabla
\ref{tbl:comandos}.

\begin{center}
\begin{table}[h]
 \begin{center}
  \rowcolors{2}{LightGray}{White}
  \begin{tabular}{ l p{4in} }
   \textbf{Comando}           & \textbf{Propósito} \\
   \toprule
    post     \index{post}     & Envía un archivo a la celda para ser almacenado.
	                            \\
	get      \index{get}      & Recupera un archivo de la celda especificando su
	                            nombre.\\
	ls       \index{ls}       & Consulta la lista de archivos que están
	                            almacenados en la celda.\\
	lls      \index{lls}      & Consulta el contenido del un directorio
	                            local.\\
	cd       \index{cd}       & Cambia el directorio de trabajo local.\\
	pwd      \index{pwd}      & Consulta el directorio de trabajo actual. \\
	adduser  \index{adduser}  & Agrega un usuario.\\
	addgroup \index{addgroup} & Agrega un grupo.\\
	whoami   \index{whoami}   & Le pregunta al sistema ¿cuál es el usuario con
	                            el que se está conectado a la celda. \\
	exit \index{exit}         & Finaliza la conexión con la celda de
	                            almacenamiento. \\
   \bottomrule

  \end{tabular}
 \end{center}
 \caption{Comandos disponibles para utilizar la celda de almacenamiento.}
 \label{tbl:comandos}
\end{table}
\end{center}

Los parámetro que necesita cada uno de estos comandos puede consultarse
directamente en el cliente, ejecutando el comando \textit{help} como se indica
en el listado \ref{lst:comandohelp}.

\begin{lstlisting}[style=consola, numbers=none, label=lst:comandohelp,
 caption=Obteniendo ayuda desde el cliente.]
celda:> help [comando]
\end{lstlisting}

Donde \textit{[comando]} es cualquiera de los comandos mostrados en la tabla
\ref{tbl:comandos}.


